<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
	<title>oak-purge-master-logs: openark kit documentation</title>
	<meta name="description" content="oak-purge-master-logs: openark kit" />
	<meta name="keywords" content="oak-purge-master-logs: openark kit" />
	<link rel="stylesheet" type="text/css" href="style.css" />
</head>

<body>
	<div id="main">
		<div id="header">
			<h1>openark kit documentation</h1>
			<div class="subtitle">Common utilities for MySQL</div>
		</div>
		<div id="contentwrapper">
			<div id="content">
				<h2><a href="oak-purge-master-logs.html">oak-purge-master-logs</a></h2>	
<h3>NAME</h3>
oak-purge-master-logs: purge master logs, depending on the state of replicating slaves.
<h3>SYNOPSIS</h3>
Retain only three binary logs:
<blockquote>oak-purge-master-logs --retain-logs=3</blockquote>
Retain three binary logs, expect two slaves, purge logs even if slaves are not up to date:
<blockquote>oak-purge-master-logs --retain-logs=3 --expect-num-slaves=2 --pro-master</blockquote>
Retain at least three binary logs, expect at least two slaves, do not delete logs which were not read by all slaves, abort if less than two slaves are found:
<blockquote>oak-purge-master-logs -r 3 --expect-num-slaves=2 --pro-slaves</blockquote>
Retain at least three binary logs, expect two slaves, do not delete logs which were not read by at least one slave:
<blockquote>oak-purge-master-logs -r 3 -n 2 --pro-master --pro-slaves</blockquote>
Same as above, but first flush logs:
<blockquote>oak-purge-master-logs --flush-logs --retain-logs=3 --expect-num-slaves=2 --pro-master --pro-slaves --print-only</blockquote>
Same as above, do not actually purge, just print out the PURGE statement:
<blockquote>oak-purge-master-logs --flush-logs --retain-logs=3 --expect-num-slaves=2 --pro-master --pro-slaves --print-only</blockquote>
Same as above, provide connection parameters, prompt for password:
<blockquote>oak-purge-master-logs --host=192.168.2.103  --user=root --ask-pass --socket=/tmp/mysql.sock -f -r 3 -n 2  --pro-master --pro-slaves</blockquote>
Same as above, use defaults file:
<blockquote>oak-purge-master-logs --defaults-file=/home/myuser/.my-oak.cnf -f -r 3 -n 2  --pro-master --pro-slaves</blockquote>
<h3>DESCRIPTION</h3>
oak-purge-master-logs is a sophisticated tool which purges master logs while considering the replicating slaves.

Purging master logs is essential in order to maintain free disk space on the master. However, purging logs which have not yet been replicated to slaves (due to slave lag, or temporary being offline) will break slave replication. This utility can handle the trade off between the master's space requirement and the slaves' replication requirement.

Breaking of replication is undesired, as it it may be a lengthy process to restore it.

There are essentially three modes in which this tool can be operated:
<ul>
	<li>--pro-master: the mater gets the higher priority. Master logs files will be purged even if some or all slaves are not up to date. When master disk space is low, this may be a proper setting.</li>
	<li>--pro-slaves: slaves get the higher priority: oak-purge-master-logs will only purge logs files which are not required by any replicating slave. This means it ensures that all slaves will safely continue replicating. When master is high on disk space, this is the proper setting.</li>
	<li>--pro-master with --pro-slaves: the combination of the two flags ensures that at least one slave is considered when purging master logs. This means that after running the utility, at least one slave will keep replicating. This setting is appropriate when master disk space is reasonable, and when at least one slave is known to be functional (while others may go offline for long periods, for example). Restoring replication on lost slaves when an existing, working replication is present is relatively easy and non-interrupting.</li>
</ul>
With --print-only, nothing is actually performed: instead, the PURGE statement is printed to standard output.

For this utility to run, the SUPER, REPLICATION CLIENT privileges are required.
<h3>OPTIONS</h3>
--ask-pass
<p class="indent">Prompt for password. The same password is expected to apply for the master and the slaves.</p>

--defaults-file=DEFAULTS_FILE
<p class="indent">Read from MySQL configuration file. Overrides --user, --password, --socket, --port.</p>
<p class="indent">The same user name &amp; password are expected to apply for the master and the slaves.</p>
<p class="indent">Configuration needs to be in the following format:</p>

<p class="indent"><strong>[client]<br/>
user=my_user<br/>
password=my_pass<br/>
socket=/tmp/mysql.sock<br/>
port=3306</strong>
</p>

-f, --flush-logs
<p class="indent">Perform FLUSH LOGS on startup</p>

-H HOST, --host=HOST
<p class="indent">MySQL master host (default: localhost)</p>

-n EXPECT_NUM_SLAVES, --expect-num-slaves=EXPECT_NUM_SLAVES
<p class="indent">Number of slaves to expect (default: 0). When --pro-slaves flag is specified, and less than expect-num-slaves slaves are found, master logs files are not purged.</p>

-p PASSWORD, --password=PASSWORD
<p class="indent">MySQL password. The same password is expected to apply for the master and the slaves.</p>

-P PORT, --port=PORT
<p class="indent">TCP/IP port (default: 3306)</p>

--pro-master
<p class="indent">Force purging of logs, even if slaves are not up to date and will cease to replicate (this may ensure that disk space on master does not run out).</p>
<p class="indent">See also: --pro-slaves together with --pro-master</p>

--pro-slaves
<p class="indent">Do not purge master logs which are not replicated by all slaves. This will ensure that even if slaves are lagging far behind, replication is not broken: master will keep all required logs to maintain replication for all slaves.</p>
<p class="indent">Together with --pro-master: master logs may be purged only as long as there is at least one slave whose replication will not break.</p>

-r RETAIN_LOGS, --retain-logs=RETAIN_LOGS
<p class="indent">Number of logs to retain on master (default: 5). The utility will keep at least that many logs files on master.</p>

--sentinel=SENTINEL_FILE
<p class="indent">When the given file exists, oak-purge-master-logs exits without doing anything. Default: /tmp/oak-purge-master-logs.sentinel</p>

--skip-show-slave-hosts
<p class="indent">When SHOW SLAVE HOSTS returns rows, these are considered the only slave hosts. Otherwise slaves are found looking at SHOW PROCESSLIST. With --skip-show-slave-hosts, only SHOW PROCESSLIST is used.</p>

-S SOCKET, --socket=SOCKET
<p class="indent">MySQL socket file. Only applies when host is localhost</p>

-u USER, --user=USER
<p class="indent">MySQL user. The same user is expected to apply for the master and the slaves.</p>

<h3>ENVIRONMENT</h3>
Requires MySQL 5.0 or newer, python 2.3 or newer.

python-mysqldb must be installed in order to use this tool. You can
<blockquote>apt-get install python-mysqldb</blockquote>
or
<blockquote>yum install mysql-python</blockquote>
<h3>SEE ALSO</h3>
oak-show-replication-status
<h3>LICENSE</h3>
This tool is released under the BSD license.
<blockquote><pre>Copyright (c) 2008 - 2010, Shlomi Noach
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
* Neither the name of the organization nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR 
TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</pre>
</blockquote>
<h3>AUTHOR</h3>
Shlomi Noach
				<br/>
			</div>
			<div id="sidebarwrapper">
				<div id="menu">
					<h3>openark kit tools</h3>
					<ul>
						<li><a title="Introduction" href="introduction.html">Introduction</a></li>
						<li><a title="Download" href="download.html">Download</a></li>
						<li><a title="Install" href="install.html">Install</a></li>
						<li><a title="oak-apply-ri" href="oak-apply-ri.html">oak-apply-ri</a></li>
						<li><a title="oak-block-account" href="oak-block-account.html">oak-block-account</a></li>
						<li><a title="oak-chunk-update" href="oak-chunk-update.html">oak-chunk-update</a></li>
						<li><a title="oak-get-slave-lag" href="oak-get-slave-lag.html">oak-get-slave-lag</a></li>
						<li><a title="oak-hook-general-log" href="oak-hook-general-log.html">oak-hook-general-log</a></li>
						<li><a title="oak-kill-slow-queries" href="oak-kill-slow-queries.html">oak-kill-slow-queries</a></li>
						<li><a title="oak-modify-charset" href="oak-modify-charset.html">oak-modify-charset</a></li>
						<li><a title="oak-online-alter-table" href="oak-online-alter-table.html">oak-online-alter-table</a></li>
						<li><a title="oak-prepare-shutdown" href="oak-prepare-shutdown.html">oak-prepare-shutdown</a></li>
						<li><a title="oak-purge-master-logs" href="oak-purge-master-logs.html">oak-purge-master-logs</a></li>
						<li><a title="oak-repeat-query" href="oak-repeat-query.html">oak-repeat-query</a></li>
						<li><a title="oak-security-audit" href="oak-security-audit.html">oak-security-audit</a></li>
						<li><a title="oak-show-limits" href="oak-show-limits.html">oak-show-limits</a></li>
						<li><a title="oak-show-replication-status" href="oak-show-replication-status.html">oak-show-replication-status</a></li>
					</ul>
				</div>
			</div>	
			<div class="clear">&nbsp;</div>
			
			<div id="footnote" align="center">
				<a href="">openark kit</a> documentation
			</div>
		</div>
	</div>
</body>
</html>
